ATSUSetTextHandleLocation

OSStatus ATSUSetTextHandleLocation (
                     ATSUTextLayout iTextLayout,
                     UniCharArrayHandle iText,
                     UniCharArrayOffset iTextOffset,
                     UniCharCount iTextLength,
                     UniCharCount iTextTotalLength);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to a valid text layout object.

iText

A handle of type UniCharArrayHandle. Pass a handle that points to the beginning of a text buffer. Note that ATSUI expects the buffer to contain Unicode text. Your application is responsible for allocating the memory associated with this handle. ATSUI functions that need to access text referenced by this handle will return the handle to its original state (locked or unlocked) upon function completion.

iTextOffset

A value of type UniCharArrayOffset. Pass the edge offset in backing store memory that corresponds to the beginning of range of text that you want ATSUI to perform layout operations on. If you want the range of text to start at the beginning of the text buffer, you should pass the constant kATSUFromTextBeginning, described in Text Offset Constant. If you want the range of text to cover the entire text buffer, pass kATSUFromTextBeginning in this parameter and kATSUToTextEnd in the iTextLength parameter. If the specified range of text is outside the text buffer, ATSUSetTextHandleLocation returns the result code kATSUInvalidTextRangeErr.

iTextLength

A value of type UniCharCount. Pass the length of the range of text that you want ATSUI to perform layout operations on. If you want the range of text to span the end of the text buffer, you should pass the constant kATSUToTextEnd, described in Text Length Constant. If you want the range of text to cover the entire text buffer, pass kATSUToTextEnd in this parameter and kATSUFromTextBeginning in the iTextOffset parameter. If the specified range of text is outside the text buffer, ATSUSetTextHandleLocation returns the result code kATSUInvalidTextRangeErr.

iTextTotalLength

A value of type UniCharCount. Pass the length of the text buffer. This value should be greater than the range of text you passed in the iTextOffset and iTextLength parameters, unless you want to perform layout operations on the entire text buffer.

function result

A result code. See Result Codes.

DISCUSSION

The ATSUSetTextHandleLocation function assigns it new text or updates existing text that is accessed by a handle. For uninitialized text layout objects, ATSUSetTextHandleLocation assigns new text; for initialized text layout objects, it updates existing text that is accessed by a handle. ATSUSetTextHandleLocation clears layout caches. If you want to assign or update text accessed by a pointer, call the function ATSUSetTextPointerLocation.

If the user deletes, inserts, or moves text in a text layout object and the range of text covers the entire text buffer, you should

call the function ATSUSetTextPointerLocation or ATSUSetTextHandleLocation to update the text
call ATSUSetRunStyle to update the style runs

You can then call the function ATSUDrawText to display the updated text.

Most functions that operate on text layout objects perform these operations on the range of text that you specify in the iTextOffset and iTextLength parameters. Typically, this is a subrange of the entire text buffer. If this range is shorter than the entire text buffer, the text layout object will scan the remaining text to get the full context for bidirectional processing and other information about the text.

SPECIAL CONSIDERATIONS

ATSUSetTextHandleLocation may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.